/*
  Copyright 1996-2003
  Simon Whiteside

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

* $Id: Executable.java,v 1.19 2003/02/27 18:00:28 simkin_cvs Exp $
*/

package simkin;
import java.util.Hashtable;

/**
 * This interface is implemented by objects which want to override the method and field access 
 * which uses Java introspection by default.
 * <p>An executable object is considered by the interpreter to consists of properties and
methods. The interface defines 3 major functions: <ul>
 * <li>{@link simkin.Executable#getValue getValue} : gets a value from the object
 * <li>{@link simkin.Executable#setValue setValue} : sets a value in the object
 * <li>{@link simkin.Executable#method method} : calls a method on the object
 * </ul>
 */
public interface Executable {
    /**
     * Called to set the value of a field. If an attribute name is given, the value is stored as an attribute of the given element, otherwise as a text value
     * @param field_name the name of the field
     * @param attrib_name the name of the attribute to be set (can be null)
     * @param value the value to be set
     * @param ctxt the context the function is called within
     * @throws RuntimeException - if there was a problem running the script (such as not having permission to access a field)
     * @throws FieldNotSupportedException - if the field could not be found
     */
    public void setValue(String field_name,String attrib_name,Object value, ExecutableContext ctxt) throws RuntimeException, FieldNotSupportedException;
    /**
     * Called to set an object into this collection.
     * @param array_index an object whose value indicates the index of the item in the collection
     * @param attrib_name the name of the attribute to be set (can be null)
     * @param value the value to be set
     * @param ctxt the context the function is called within
     * @throws RuntimeException - if there was a problem running the script
     */
    public void setValueAt(Object array_index,String attrib_name,Object value, ExecutableContext ctxt) throws RuntimeException;
    /**
     * Called to get the value of a field
     * @param field_name the name of the field
     * @param attrib_name attribute name (null if no attribute specified)
     * @param ctxt the context the function is called within
     * @return the value of the field (or null, if the field is not supported)
     * @throws RuntimeException - if there was a problem running the script (such as not having permission to access a field)
     * @throws FieldNotSupportedException - if the field could not be found
     */
    public Object getValue(String field_name,String attrib_name, ExecutableContext ctxt) throws RuntimeException, FieldNotSupportedException;
    /**
     * Called to get the value of an object in this collection
     * @param array_index an object whose value indicates the index of the item in the collection
     * @param attrib_name attribute name (null if no attribute specified)
     * @param ctxt the context the function is called within
     * @return the value of the object (null if not present)
     * @throws RuntimeException - if there was a problem running the script 
     * @throws FieldNotSupportedException - if the field could not be found
     */
    public Object getValueAt(Object array_index,String attrib_name, ExecutableContext ctxt) throws RuntimeException;
    /**
     * Called if a Simkin script calls a method on this object. 
     * @param method_name the name of the method
     * @param arguments an array of arguments passed to the method
     * @param ctxt the context the function is called within
     * @return the function's return value
     * @throws RuntimeException - if there was a problem running the script (such as divide by zero)
     * @throws NoSuchMethodException - if the method could not be found
     */
    public Object method(String method_name,Object[] arguments, ExecutableContext ctxt) throws ParseException, RuntimeException, MethodNotSupportedException;
    /** This method returns an ExecutableIterator object which is used in a foreach statement. This version is unconditional.
     * @return a new iterator object, or null if this object cannot be iterated
     */
    public ExecutableIterator createIterator();
    /** This method returns an ExecutableIterator object which is used in a foreach statement. This version is qualified by a string which can be interpreted in any way.
     * @param qualifier - a string that can be used to qualify the iteration in any way
     * @return a new iterator object, or null if this object cannot be iterated
     */
    public ExecutableIterator createIterator(String qualifier);
    /**
     * This method returns the source for a scripted method described by the location
     * @param location the location of the method - in the format passed to the execute functions in the Interpreter
     * @return the source for the method
     */
    public String getSource(String location);
    /**
     * This method returns the instance variables for this object
     * @return table a table to filled with references to the instance variables. Each entry in the table maps a name to an object
     */
    public Hashtable getInstanceVariables();
    /**
     * This method returns the attributes for this object
     * @return table a table to filled with the attribute values. Each entry in the table maps an attribute name to a value
     */
    public Hashtable getAttributes();
};
